home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Risc World 3
/
Risc World 3.iso
/
SOFTWARE
/
ISSUE4
/
ZAP
/
!Zap
/
Modules
/
!ZapMJE
/
!Help
next >
Wrap
Text File
|
2002-09-18
|
17KB
|
437 lines
ZapMJE 0.80 help file
© Martin Ebourne, 1997 - 1999
© Zap Developers, 2000 - 2002
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
The General Public License is included as !ZapMJE.Copying. Source is available
via CVS; see <http://zap.tartarus.org/cvs> for more information.
Introduction
============
ZapMJE provides several new modes and various other extensions for the Zap
text editor. In brief, these are:
• C, C++, Java, Acorn Assembler, and Pascal source editing modes
• Colour, compilation, indenting, bracket matching, function browsers,
next/last function, swap to header, auto header file generation, improved
shift-left and right cursor (previous and next word), auto mode
detection, ensuring linefeed termination, and various commenting features
for the new modes (not all features in all modes)
Please note that ZapMJE requires Zap version 1.42 or greater to work.
Mode specific features
==== ======== ========
Colour
------
This is currently available in the C, C++, Java, and assembler modes. Pascal
will be implemented one day (when someone has told me or I have figured out
the precise syntax). For C/C++/Java, the colours are as follows:
Foreground : Used for anything which doesn't classify below
Comments : Anything in /* */, or after // for C++/Java
Strings : Strings, character constants and include filenames
(ie. anything in "", '' or, after a #include, <>)
Instructions: Reserved words (eg. switch, void)
Preprocessor: Anything on preprocessor lines not under any other category
(including preprocessor keywords such as #define). Its use
in Java mode is optional (MJE_PREPROSET).
Functions : Function name in definitions, calls and macros. Not however,
when used as a pointer
Variables : Any other user defined word, including parameter-less macros
Numbers : Things like 6.5!
The assembler colours are:
Foreground : Used for anything which doesn't classify below
Comments : Anything after ;
Strings : Strings and character constants (ie. anything in "" or '')
Instructions: Anything in the instruction field (first section of line
following whitespace), plus anything else which is part of
the instruction (eg. {, }, !). Also instruction shifts
(eg. ASL)
Operators : Assembler expression operators (eg. :SHL:)
Labels : Anything in the label field (text at very start of line)
Names : Any user defined words in the parameters of an instruction
Numbers : Things like 2_1101
Colouring is automatic, and if you want to switch it off you will have to set
all the foreground colours the same. A problem you are bound to have in 16
colour modes is finding enough useable colours to display. In C they are best
as all different (in assembler some of them are very closely related and
hence are best coloured the same), but unfortunately there are only 5 usable
colours in the normal Wimp palette. Hence the defaults are designed for 256+
colour modes and I've no idea what they'll look look like in 16 colours. If
using 16 colour modes, I recommend you re-define the colours in the palette
to include some useable ones.
Please note that the colouring is defined to colour CORRECT source code
correctly. What it does with incorrect source is arbitrary since then even
the compiler/assembler will not accept it and it is hence not source code.
Compilation
-----------
This is quite powerful and is designed to cater for most situations. The way
it operates is as follows (in order):
1. Look for sourcefile.^.^.MakeFile (standard name and location for a
makefile)
2. If it is type Text (FFF) or Makefile (FE1) then pass it round as a message
Data Open for either Make or AMU to pick up on. Note that it is passed round
as type FE1 regardless of whether it is Text or not. This is because a lot of
makefiles are typed to Text, and Make and AMU will not pick these up (but Zap
will!). Also note that for AMU to intercept this message, it needs a
'filetype &FE1;' line inserted into the top section of the description file.
3. If no task claims the message then amu is invoked from the command line in
a task window. The default amu options used are '-desktop -k'. The taskwindow
options used are '-display -quit'.
4. If sourcefile.^.^.MakeFile file is not of type Text or Makefile, then it
is run using Wimp_StartTask. This allows for obey files and the like to be
used, giving absolute flexibility.
5. If sourcefile.^.^.MakeFile file does not exist, then the source file is
compiled/assembled direct. It cannot be passed round as a Wimp message
because it is text, and so cannot be claimed by CC or whatever. Thus it is
compiled/assembled in a task window along the same lines as amu if invoked
above. The options used depend on the mode and are as follows:
C - '-IC: -throwback -LC:o.RISC_OSlib,C:o.stubs -Desktop ^'
Asm - Assembly does not work at the moment. Makefiles are still ok
though
Pascal - '-ranprv -LC:o.Stubs -throwback -desktop ^'
6. There is one last feature to ensure 100% flexibility. If the characters
'/*+ ', ';+ ' or '(*+ ' (depending on mode) are found within the first 1k of
the source file when invoking amu or compilation/assembly directly in a task
window, then the following characters until the next close comment or end
of line are used INSTEAD of the default options string. This means that if
you don't like the default options, you can supply your own. (For instance,
if you include extra libraries or want debug code generated.)
Note that the maximum length for the command issued is 255 characters,
including the filename, commands and the various options. Also, NO
translation is carried out in copying the options. However, when calling
*TaskWindow, the command is placed in quotes - so if any were required in the
options string they would have to be doubled up originally.
There are two commands to invoke compilation; COMPILE which saves and then
compiles (assuming the save was ok), and RUN which compiles without saving
the current file. (These correspond to the equivalent BASIC commands.)
Indenting
---------
This is currently only present in C, C++ and Java modes, and simply puts the
requested number of extra spaces onto the indent for the line following a {,
and aligns }s up with the corresponding {. The indent is set via the mode
menu, and should have the value 0 to disable the feature.
Comments are optionally reindented (MJE_INDENTCOMMENTSET).
Bracket matching
------- --------
There are two types of bracket matching available, which both work on all
three kinds of bracket (ie. ), }, and ]) and in all modes.
With as you type matching the cursor jumps to the corresponding open bracket
for the time specified in the pause entry in the mode menu (in centiseconds)
whenever you type a close bracket. The pause will be truncated if you carry
on typing, and the matching can be disabled completely by setting the delay
to 0.
Bracket highlighting highlights a pair of brackets when the cursor is
immediately to the right of either of the pair. The brackets are highlighted
by setting their background to the colour specified under 'Brackets' in the
colour menu. To disable highlighting set the colour to be the same as the
background colour.
Function browsers
-------- --------
This feature works on all except the C++ and Java modes, and simply provides
a browser of all the function definitions in the source file. C mode
correctly copes with old and new style function definitions, as well as
contrived statements such as:
#ifdef __STDC__
int wibble(int wobble)
#else
int wibble(wobble)
int wobble;
#endif
{
...
which are designed to work under both pcc and ANSI compilers. Assembler mode
simply lists all the lines on which labels are defined. This feature is
invoked with the standard command LISTFNS.
Next/last function
---- ---- --------
These work in the same way as the function browser, but place the cursor at
the definition of the next or previous function in the source file. They are
invoked with MJE_NEXTFUNC and MJE_LASTFUNC respectively.
Swap to header
---- -- ------
This moves the input focus onto the corresponding header/source file (ie.
with the same leafname) for the current source/header file (assuming one
exists). It also loads the file if necessary. The corresponding header file
is of the form sourcefile.^.^.h.sourcefile, and the corresponding sourcefile
is of the form headerfile.^.^.x.headerfile where x is c, c++, j, s, or p
depending on mode. This feature is invoked with MJE_SWAPTOHEADER.
Auto header file generation
---- ------ ---- ----------
This is only in its simple stages at the moment, but on executing
MJE_GENERATEHEADER (C mode only), function prototypes will automatically be
generated and appended to the respective header file (see MJE_SWAPTOHEADER).
The prototypes are appended immediately after the first occurrence of the
sequence '/* Auto */', deleting everything following it. If the sequence is
not found in the file, then it will be appended along with the prototypes.
Currently this only deals with functions, but variables will be included at a
later date. Note also that if the header file does not exist, one will NOT be
created. This is done deliberately so that you can't accidentally generate
unwanted header files.
Previous and next word
-------- --- ---- ----
The previous and next word commands (shift-left & shift-right) of Zap are
intended for use when text editing, and as such only stop after whitespace or
parentheses. This is fine for text, but totally unsuitable for program
editing unless you are liberal with your spaces (I'm not). For instance,
previous/next word would jump right over 'whatever=this+that/something_else;'
which is not very useful. For that reason all of the extra modes have a much
more powerful implementation as standard. It can be thought of as working
like this:
There are 5 categories of character, classified in descending order as:
5: Newline character
4: Letters and numbers
3: Anything else non-whitespace (ie. symbols)
2: Whitespace (space and tab)
1: Newline character
When you press shift-left or shift-right, the cursor will be moved in that
direction until the classification of the next character (in the direction it
is moving) is greater than that of the current character, upon which it will
stop. Newline appears twice in order to ensure that the cursor will always
stop on each side of it. (ie. at start & end of line).
This probably sounds quite complicated, but it is in actual fact very easy,
and very intuitive to use. As an example, these are the points that the
cursor would stop at:
Line: if((char2=getchar())!=0 && char2!=line_terminator)
Fwd :^ ^ ^ ^ ^ ^ ^ ^ ^ ^
Back:^ ^ ^ ^ ^ ^ ^ ^ ^^
Auto mode detection
---- ---- ---------
This is provided so that header files are loaded into the correct mode.
Currently Zap can only detect mode on filetype and file name. However, header
files have type text and are in a h directory, but they can be any of the
five modes. Thus if header files are set to C then on loading if a C++,
assembler, or Pascal comment is found as the first non-whitespace character
in the file, the appropriate mode will be used instead.
Linefeed termination
-------- -----------
This quite simply ensures that there is a linefeed at the end of your file
whenever you save it, in order to prevent the compiler from throwing an error
and you having to re-compile for something so simple. It is functional in all
four modes.
Various commenting features
------- ---------- --------
These all work in all four modes and are:
MJE_OPENCOMMENT
This inserts the appropriate open comment text (ie. '/* ', '// ', '; ' or
'(* ').
MJE_CLOSECOMMENT
Inserts appropriate close comment (' */' or ' *)' [none for C++ and
assembler]).
MJE_COMMENT
This inserts both the start and end comments leaving the cursor in the
middle.
MJE_IF
Inserts 'pre-processor comment'. ie. uses conditional compilation/assembly
to effectively comment out the stuff ahead.. (Handy if there are comments
around, since you can't nest them in C). Inserts '#if 0\n' or ' [ 1=0\n'
depending on mode.
MJE_ENDIF
Finishes 'pre-processor comment'. (ie. inserts '#endif\n' or ' ]\n'.)
MJE_COMMENTLINE
Comments out line and moves onto next. (ie. inserts '/* ' & ' */', '// ',
'; ', or '(* ' & ' *)' at start and end of line.)
MJE_UNCOMMENTLINE
Reverses above. (ie. removes '/* ' & ' */', '// ', '; ', or '(* ' & ' *)'
if present and moves onto next line)
Where a language has two different possible comment styles, the command
MJE_COMMENTSET allows you to select the alternative one.
Non-standard option
--- -------- ------
This will not be very useful to many people, except if they lay their
assembler source out the same way as I do. Basically, if enabled then on
pressing tab you will be advanced to the next 'source column' rather than tab
stop. It only works sensibly with Unix or column tab, and the 'source
columns' are laid out as follows (using Unix tab):
Label ->------->Ins --->Operands ------>------->------->Comment
(ie. 2, 1 and 4 tab stops)
If your source looks like that, then try it, you might like it. If it doesn't
then don't switch it on and no harm done. The only reason it is in there is
because it is easier than disabling it for release. Also, Dominic wanted me
to use the non-standard option in order to justify its existence. I bet he'll
remove it now just to spite me. ;-) This feature is probably only a stop-gap
until Zap supports variable tab stops properly.
Optional behaviour
-------- ---------
MJE_COMMENTSET, MJE_INDENTCOMMENTSET and MJE_PREPROSET let you toggle
various optional behaviours, as noted earlier. They in general should only
be used in the menus file, as supplied. Briefly, they take a word argument
which has the internal mode number in the top halfword, with the bottom
halfword clear.
Note to mode authors
==== == ==== =======
Do not use any of the modes in this module as base modes - it will not work.
This is due to the way that the same code is re-used for all of the modes. If
you want a similar mode to these then contact me and maybe it can go in the
module. Adding a new mode which takes advantage of the commenting, function
finding, compiling, etc. requires nine ARM instructions and is therefore very
easy and efficient. Mode specific features, such as colouring, need extra
code.
ZapMJE also provides support for writing less speed critical routines in C to
reduce development time for your modes. However, again these facilities are
available only within the module.
Acknowledgements
================
Thanks to Dominic for writing Zap and not even charging for it! (Though he's
partly responsible for a rather large amount of damage to my 'phone bill.
:-()
Thanks to Brian Scattergood for writing his Cmode which this originally came
from - it made initial development a lot easier (although I did have to hack
it first :-]). There's even some original (slightly modified) code left! This
will have to be replaced in the course of making it work on all modes sooner
or later. :-(
Contacting
==========
Please address bug and features requests to <bugs@zap.tartarus.org> and
<zap-features@zap.tartarus.org> respectively. For test versions (identified in
the module help string), bugs should be sent to <betabugs@zap.tartarus.org>.
If you are unable to use email, please see the main Zap manual for a postal
address to write to.
Known mis-features
===== === ========
(These are just the important ones :-()
Assembler:
• Assembling with no make file doesn't work
• Function finding cheats (uses search)
C/C++:
• Auto header generation is very basic (yes, it's intentional!)
• The syntax colouring is slow with large files and multiple views of the
same file, but then when constructs such as:
#inc\
lude /* *\
/ <std\
io.h>
are valid (try it, it works!), it's hardly surprising. However, this will
be improved in later versions.
• Problems with function finding:
1) Preprocessor # not at start of line not recognised
2) foo () isn't found
3) It doesn't cope with \ outside of preprocessor
These 'bugs' are due to me not knowing precisely how the C syntax worked
when I wrote it
• Typing } after this sequence causes it to get locked into a loop:
a{
a
• The header generation copies static functions into the header
• There are a multitude of bugs in the colouring, but I bet you won't find
many! :-)
Pascal:
• Function finding cheats (like assembler)